Issue: listWebLLMModels does not call assertBrowserEnvironment() unlike isWebLLMModelCached, deleteWebLLMModel, and downloadWebLLMModel. This is inconsistent — if the module can't be loaded in Node, it will throw WebLLMUnavailableError from loadWebLLMModule() anyway, but the error message won't be the clear "requires a browser" guidance.

Suggestion: Either add assertBrowserEnvironment() for consistency with the other helpers, or add a code comment explaining why listWebLLMModels intentionally skips the check (e.g., if it's designed to work in server-side contexts for listing available models without needing WebGPU).

Issue: The mapChunkToEvents, extractUsage, and the streaming state management logic here are nearly line-for-line identical to mapChatChunkToEvents in src/models/openai/chat-adapter.ts. This creates a maintenance burden where fixes to one must be duplicated to the other.

Suggestion: Consider extracting the shared OpenAI-compatible chunk-to-event mapping into a shared utility (e.g. src/models/openai-compatible-streaming.ts) that both the OpenAI chat adapter and WebLLM can import. At minimum, leave a // NOTE: comment cross-referencing the OpenAI adapter so future maintainers know to keep them in sync.

Issue: The model_type access uses a double cast through unknown ((record as unknown as { model_type?: string }).model_type), which is fragile and circumvents type safety.

Suggestion: Since ModelRecord comes from @mlc-ai/web-llm types, either:

1. Use optional chaining with an in check: if ('model_type' in record && typeof record.model_type === 'string')
2. Or extend the ModelRecord type locally if this field is expected but not yet typed upstream

The current double-cast could silently break if model_type is renamed or restructured.

Issue: The stream method catches errors from the engine and re-throws via normalizeError(error), but if the error occurs during iteration of the async iterable (inside for await), the generator will be in a partially-yielded state. The consumer will see the error, but any buffered modelContentBlockStartEvent won't have a matching modelContentBlockStopEvent, which could leave the SDK's message accumulator in an inconsistent state.

Suggestion: Consider emitting content block stop events in the catch/finally block when state.textContentBlockStarted is true or activeToolCalls is non-empty, to ensure the stream is always well-formed even on errors.

Issue: The peer dependency is specified as "^0.2.79" which for a pre-1.0 package (semver treats 0.x specially) only allows 0.2.x patches. This is correctly conservative. However, @mlc-ai/web-llm has a history of frequent breaking changes within minor versions (their API changed between 0.2.x releases).

Suggestion: Consider whether pinning more tightly (e.g. ~0.2.79 or exact 0.2.79) would be safer, or alternatively document in the module TSDoc which web-llm API surface you depend on. If the intent is to support a range, add a comment in package.json or the README noting the tested/verified version range.

Issue: If the stream starts emitting content deltas without a preceding role delta (e.g. some engines skip the role chunk), no modelMessageStartEvent is ever emitted, but content block events are still produced. This would leave the SDK's stream consumer in an inconsistent state.

Suggestion: Add a guard that emits a synthetic modelMessageStartEvent with role: 'assistant' when content arrives before a role delta, similar to how the text content block start is auto-emitted:

if (delta?.content && delta.content.length > 0) {
  if (!state.messageStarted) {
    state.messageStarted = true
    events.push({ type: 'modelMessageStartEvent', role: 'assistant' })
  }
  // ...
}

Issue: The _createEngine method calls assertBrowserEnvironment() synchronously, then loadWebLLMModule() which also surfaces an environment error. However, when _getEngine() is called, it caches the promise — if the first call fails (e.g., module not found), it correctly resets _enginePromise allowing retry. But assertBrowserEnvironment() will always throw synchronously in Node, meaning the retry logic is unreachable in that scenario. This is fine but worth noting that the catch reset on line 300 only helps for transient loadWebLLMModule failures, not environment failures.

No action required — just noting for clarity that the retry semantics only apply to module loading/engine init failures in a valid browser environment.

Issue: assertBrowserEnvironment() checks typeof window === 'undefined' to detect non-browser environments. However, some server-side runtimes (Cloudflare Workers, Deno Deploy) and test environments (jsdom) define window without actually having WebGPU. Conversely, Web Workers (where WebGPU is available) don't have window.

Suggestion: Consider checking for typeof navigator !== 'undefined' && 'gpu' in navigator (or at minimum typeof globalThis.navigator !== 'undefined') as a more accurate browser+WebGPU heuristic, or simply let the CreateMLCEngine call surface WebLLM's own environment check (which it already does) and remove the preemptive check. The error message could also mention Web Workers as a valid environment.